Loading TOC...

POST /manage/v2/databases/{id|name}

Summary

This resource address can be used to clear the contents of the named database and to perform various configuration operations on the database. The database can be identified either by id or name.

URL Parameters
format The format of the posted data. Can be either html, json, or xml (default). This parameter is not meaningful with view=edit. This value overrides the Accept header if both are present.
overwrite-replicas This parameter is used when invoking the add-foreign-replicas operation and specifies whether to overwrite replicas with existing data. This is false by default, which specifies not to overwrite replicas with existing data. If true, then replicas with existing data are overwritten.
Request Headers
Accept The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type The MIME type of the data in the request body. Depending upon the value of the format parameter or Accept header, one of application/xml, application/json, or text/html.
Response Headers
Content-type The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, one of application/xml, application/json, or text/html.

Response

Upon success, MarkLogic Server returns status code 202 (Accepted). If the payload is malformed, a status code of 400 (Bad Request) is returned. A status code of 401 (Unauthorized) is returned if the user does not have the necessary privileges.

Required Privileges

This operation requires one of the following:

Required Privileges

All operations require the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

The available database operations are summarized in the following list. The details on each operation follow.

Clear Database

The following operation clears the database. 


     {
       "operation": "clear-database"
     }

Backup Database

The following operation initiates backup on database. The operation and backup-dir properties are required. The incremental-dir, journal-archiving, journal-archive-path, and lag-limit properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be backed up. If incremental is true, then an incremental backup is performed, otherwise a full backup is performed. It is an error to specify incremental-dir if incremental is false.

If include-replicas is true, then any replica forests are backed up, otherwise they are not backed up. 


    {
      "operation": "backup-database",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "include-replicas": "true",
      "lag-limit": 30,
      "password": "yourpassword"
    }

Validate Database Backup

The following operation validates that the database can be backed up to the backup data directory. The operation and backup-dir properties are required. The incremental-dir, journal-archiving, journal-archive-path, and lag-limit properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be validated for back up. If incremental is true, then an incremental backup is performed, otherwise a full backup is performed. It is an error to specify incremental-dir if incremental is false. If include-replicas is true, then replica forests are included in the validation, otherwise they are not included. 


    {
      "operation": "backup-validate",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "include-replicas": false,
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "lag-limit": 30
    }

Backup Status

The following operation checks the status of the outstanding backup job with the specified backup job ID. The operation and job-id properties are required. The host-id property is optional.

The request body looks like: 


    {
      "operation": "backup-status",
      "job-id": "12345678910",
      "host-name": "my-host"
    }

The response body looks like: 


    {
      "job-id": "12345678910",
      "host-name": "my-host",
      "status": "in-progress"
    }

Backup Cancel

The following operation cancels in-progress backup job with the specified backup job ID. The operation and job-id properties are required.

The request body looks like: 


    {
      "operation": "backup-cancel",
      "job-id": "12345678910"
    }

The response body looks like: 


    {
      "job-id": "12345678910",
      "canceled": true
    }

Purge Old Backups

The following operation purges old backups from the specified directory. The operation, backup-dir, and keep-num-backups properties are required. The backup-dir property specifies the directory under which to look for backups. The keep-num-backups property specifies the maximum number of old backups to keep.

The request body looks like: 


    {
      "operation": "backup-purge",
      "backup-dir": "/path/to/somewhere",
      "keep-num-backups": 3
    }

The response body looks like: 


    {
      "purged": true
    }

Restore Database

The following operation initiates an asynchronous restore of a database from the backup data directory. The operation and backup-dir properties are required. The incremental, incremental-dir, journal-archiving, journal-archive-path, and restore-to-time properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be restored. If incremental is true, then an incremental restore is performed, otherwise a full restore is performed. It is an error to specify incremental-dir if incremental is false.

If include-replicas is true, then any replica forests are restored, otherwise they are not restored.

The request body looks like: 


    {
      "operation": "restore-database",
      "forest": [
        "a",
        "b"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "restore-to-time": "2014-03-14T15:00:00Z",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "include-replicas": "true",
      "password": "yourpassword"
    }

Validate Database Restore

The following operation validates that the database can be restored from the backup data directory. The operation and backup-dir properties are required. The incremental, incremental-dir, journal-archiving, journal-archive-path, and restore-to-time properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be validated for restore. If incremental is true, then an incremental restore is validated, otherwise a full restore is validated. It is an error to specify incremental-dir if incremental is false.

The request body looks like: 


    {
      "operation": "restore-validate",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "restore-to-time": "2014-03-14T15:00:00Z",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "password": "yourpassword" 
    }

The response body is a summary of the restore set.

Restore Status

The following operation checks the status of the outstanding restore job with the specified restore job ID. The operation and job-id properties are required. The host-id property is optional.

The request body looks like: 


    {
      "operation": "restore-status",
      "job-id": "12345678910",
    }

The response body is a description of the job status.

Cancel Database Restore

The following operation cancels in-progress restore job with the specified restore job ID. The operation and job-id properties are required.

The request body looks like: 


    {
      "operation": "restore-cancel",
      "job-id": "12345678910"
    }

The response body looks like: 


    {
      "job-id": "12345678910",
      "canceled": true
    }

Merge Database

The following operation initiates a merge on the database.

The request body looks like: 


    {
      "operation": "merge-database",
    }

There is no response body. Check the status view to find out if the merge is still in progress.

Reindex Database

The following operation initiates a reindex on the database.

The request body looks like: 


    {
      "operation": "reindex-database",
    }

There is no response body. Check the status view to find out if the indexing is still in progress.

Set Database Defaults

The following operation sets the defaults on the database.

The request body looks like: 


    {
      "operation": "set-database-defaults",
    }

There is no response body.

Add Foreign Replica to Database Replication Configuration

The following operation adds a foreign replica to the database replication configuration for the database. The overwrite-replica property is false by default, which specifies not to overwrite replicas with existing data. If true, then replicas with existing data are overwritten. The foreign-database-name specifies the name of the foreign database to be used as the replica and foreign-cluster-name is the name of the foreign cluster that holds the replica database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. For an example use of this operation, see Setting the Master and Replica Databases in the Scripting Administrative Tasks Guide. 


    {
      "operation": "add-foreign-replicas",
      "foreign-replica": [
        {
          "foreign-cluster-name": "localhost-cluster",
          "foreign-database-name": "Documents",
          "connect-forests-by-name": true,
          "lag-limit": 23,
	  "enabled": true,
	  "queue-size":10
        }
      ]
    }

Remove Foreign Replica from Database Replication Configuration

The following operation removes a foreign replica from the database replication configuration for the database. The foreign-database-name property contains the name of the foreign database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. 


    {
      "operation": "remove-foreign-replicas",
      "foreign-database-name": [
        "Documents"
      ]
    }

Add Foreign Master to Database Replication Configuration

The following operation adds a foreign master to the database replication configuration for the database. The foreign-database-name is the name of the foreign database and foreign-cluster-name is the name of the foreign cluster that contains the foreign database. Specify true for connect-forests-by-name if the forest names are the same on the Master and Replica clusters, otherwise specify false. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. For an example use of this operation, see Setting the Master and Replica Databases in the Scripting Administrative Tasks Guide. 


    {
      "operation": "set-foreign-master",
      "foreign-master": {
        "foreign-cluster-name": "replica",
        "foreign-database-name": "Documents",
        "connect-forests-by-name": true
      }
    }

Remove Foreign Master from Database Replication Configuration

The following operation removes a foreign master from the database replication configuration for the database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. 


    {
      "operation": "remove-foreign-master",
    }

Example


curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/json" \
-d '{"operation":"clear-database"}' http://localhost:8002/manage/v2/databases/MyNewDatabase

==>  Clears the contents of the "MyNewDatabase" database.

Example


curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/json" \
-d '{"operation": "remove-foreign-master"}' \
http://localhost:8002/manage/v2/databases/Documents

==>  Removes the Foreign Master from the "Documents" Database 
     Replication Configuration.

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.